home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d27 / eset21.arc / ESET.DOC < prev    next >
Text File  |  1990-10-10  |  13KB  |  320 lines
  1.                          Enhanced SET command
  2.     Copyright (c) 1990 Wayne D. Mingee       All rights reserved
  3.  Archive ESET21  Program ESET v2.1  Suggested donation $10.00
  4.  
  5.                                  OVERVIEW
  6.  
  7. This program manages DOS [and 4DOS] environment variables. It will:
  8.   -Handle the master or local [secondary] environment. It does find
  9.      them all including Wyse 3.1.
  10.   -Multiple operands per line
  11.   -Set a variable to:
  12.      System date or time
  13.      Whether under a secondary command processor
  14.      A substring of a string
  15.   -Append or Prepend a string
  16.   -Arithmetically process by:
  17.      adding a +-value
  18.      shifting the value left/right n positions
  19.      And/Xor with a value
  20.   -Change a one or all occurrences of a string to another
  21.   -Take user input from Stdin with:
  22.      Issue a prompt message
  23.      limiting time to start replying and input to certain characters
  24.      limiting length of input and terminating input when input full
  25.   -Trim leading/trailing blanks from result
  26.   -Convert to upper case
  27.   -No limit on length of variables.
  28.   -Display the environment with size, used and free totals and returns
  29.      the free amount in a variable
  30.   -Works with DOS 2.0+, 4DOS and should work in a OS/2 DOS box.
  31. Registration gets additional programs that:
  32. -Manipulate I/O ports. Can be used to test printer status, carrier
  33.  detect, etc. rearrange bios port addresses.
  34. -Get file information, path, size, date, etc. Do a findfirst/findnext.
  35. -Reallocate the environment size. Release unused copies. Fix the size.
  36. -Maintain a lifo/fifo list in a variable.
  37. -Release the environment of TSR's that don't.
  38. -Commit system specs, drives, etc, to variables at boot.
  39. -Library routine for doing environment work.
  40.  
  41.                              QUICK START
  42.  
  43. ------------------------------- NOTE -------------------------------
  44.     This program will create variables longer than 127.  Care must
  45. be used when intermixing the use of the DOS SET command, since DOS
  46. will only process the first 127 positions and may leave an invalid
  47. variable in the environment.  Also variables can contain characters
  48. which DOS may not handle correctly.
  49. --------------------------------------------------------------------
  50.      If using 4DOS you must either rename ESET or disable the 4DOS
  51. command with SETDOS /I-ESET.  Also to use the prepend operation (^)
  52. you have to change the 4DOS command separator character with SETDOS
  53. /Cc.
  54. --------------------------------------------------------------------
  55.  
  56.     To test if ESET will find the environments on your system:
  57.          COMMAND /C ESET /DX Z=$C Z+=
  58.        the display should be:
  59.          [xxx] Z=1           xxx should be a hex number > 15
  60.          [xxx] Z=1           the 2nd assignment insures it was set
  61.  
  62.     To set a variable: ESET name=value
  63.     To clear a variable: ESET name=
  64.     To display the contents of the environment: ESET
  65.     To take user input into a variable: ESET name "prompt message"
  66.     To edit a variable: ESET /E name ? 155
  67.     To get current date: ESET NOW=$D
  68.  
  69.                         PARAMETER DESCRIPTIONS
  70.  
  71.     ESET name=value
  72.  
  73.     Multiple sets of arguments can be supplied:
  74.         ESET [sws] [vbl] [sws] [vbl] . . .
  75.  
  76.     All variable names are converted to upper case. Names cannot begin
  77. with a switch character.
  78.  
  79.     The switch character "/" used in these docs is actually replaced
  80. by the switch character defined in DOS.
  81.  
  82.     Switches may be given separately or in a string. ie: /C /D /CD
  83.  
  84.     To set a value containing blanks or <>| enclose the ENTIRE
  85. parameter in "". ie: ESET "NAME=Now is the time"
  86. Setting  ESET NAME="Now is the time" would include the quotes as part
  87. of the variables value.
  88.  
  89.     If no parameters other than switches are given the contents of the
  90. named environment are displayed.  There is no end of screen pause as
  91. this is designed primarily for saving the environment to a file.
  92.  
  93.     All output is to Stdout and may be redirected.
  94.  
  95.     Any token may be created from one or more environment variables.
  96. (ie: %Z% %Z%%X% %Z%--%X%) In BAT file use %%. If no closing % is found
  97. before the end of the token, ie: %%NAME one is inserted and no error
  98. is indicated.  This can help to reduce the length of command line.
  99. Also on very long variables use %% so that DOS does not include it as
  100. part of the command line.  The /M switch also effects where variables
  101. are copied from. Given ESET /M Z=%Y% then Y would be copied from the
  102. master environment.
  103.     All variables are resolved including those within "".  To include
  104. a % as part of a variable you have to use 2 %% [3 in BAT files].
  105. Included variables are not tested for variables.
  106.  
  107.      Default settings can be set in an environment variable equal to
  108. the program name.  This works even if ESET is renamed.
  109.  
  110.  
  111. GENERAL SWITCHES
  112.  
  113. /U the value is converted to upper case.
  114.  
  115. /C a LF is output on STDOUT. This occurs immediately for each C
  116. encountered.  Can be used to separate user input on separate lines.
  117. ie: ESET FNAME "Enter file name>" /C CNAME "Enter customer name" /C
  118. ESET does not normally end any display with a CRLF thus allowing you
  119. to control the display.
  120.  
  121. /T the requested operation is performed and then all leading and
  122. trailing blanks are removed from the value.
  123.  
  124. /D the results are displayed on stdout as name=value with one trailing
  125. space but no CRLF.
  126.  
  127. /X the hex value of the return code for each operation is displayed on
  128. stdout as [xxx].  If less than 16 then it is an error code otherwise
  129. it is the displacement of the variable into the environment.
  130.  
  131. /M the master environment is used instead of the local [secondary]
  132. shell's.  If operating under the primary shell it has no effect.
  133. Remember when setting the master environment while under a secondary
  134. shell that the new value will not be available to normal DOS batch
  135. commands since the local environment was not affected.  Use the /R
  136. switch to set both.
  137.  
  138. /R after the operation is performed the resultant value is copied to
  139. the master environment.  If operating under the primary shell it has
  140. no effect.
  141.  
  142. /B processing is terminated with ERRORLEVEL 3 if any error has
  143. occurred up to this point.
  144. ie: ESET PATH*=/C:\ESET;/C:\ESET;/ /B
  145. would return ERRORLEVEL 3 if the PATH does not contain the directory
  146. C:\ESET
  147.  
  148. /N processing is terminated with ERRORLEVEL 3 if no error has occurred
  149. up to this point.
  150. ie:  ESET PATH*=/C:\ESET;/C:\ESET;/ /N PATH^=C:\ESET;
  151. would prepend the directory C:\ESET to the PATH if it does not already
  152. exists in it.
  153.  
  154. Switches UMDXTR are toggles. Each occurrence reverses the state.
  155.  
  156. If the value begins with a $ then ESET will perform certain special
  157. functions to create the value. To set a value beginning with a $ use
  158. two $.   The $ codes are:
  159.  
  160.    $D - returns current date mm-dd-yyyy
  161.    $T - returns current time hh:mm:ss
  162.    $Sn1,n2,string - returns substring of variable starting at n1 for
  163.          n2 positions. 1 = position 1.
  164.    $+ [+/-]n2 -  add integer n2 to variable
  165.    $& [+/-]n2 -  and integer n2 to variable
  166.    $^ [+/-]n2 -  xor integer n2 to variable
  167.    $[ [+/-]n2 -  shift variable left n2 bits
  168.    $] [+/-]n2 -  shift variable right n2 bits
  169.    $C  - returns a 0 if running under the primary command
  170.          processor and a 1 if it is a secondary.
  171.    $E  - gets value of byte at 40:F0 which if you are using RELENV
  172.          [available in the registered version] is the return code of
  173.          last program termination.
  174.  
  175. If the name ends in one of the following characters the special
  176. operation is performed with the value. To end a name in one of these
  177. use 2. [name**]
  178.  
  179.    -     remove value from variable
  180.    ^     prepend value to variable
  181.    +     append value to variable
  182.    *     value is in two parts separated by a delimiter equal to the
  183.          first char. The first occurrence of the first part is
  184.          replaced by the second part. ie: /yy/xx/  replaces yy with
  185.          xx. Replacing a NULL string is the same as prepend.
  186.          Replacing a NULL with a NULL will return ERRORLEVEL 0 if the
  187.          VARIABLE exists and a 1 if not.
  188.    @     same as * but changes all occurrences. Replacing a NULL
  189.          string will make the variable fill up the unused space in the
  190.          environment.
  191.  
  192. ERRORLEVELS RETURNED
  193.  
  194. 1    problem setting environment variable
  195.          name* - old value not found
  196.          name- - value not found
  197.      processing continues
  198.  
  199. 2    problem processing the command
  200.          syntax error
  201.          could not find the environment
  202.          insufficient space in environment
  203.      processing terminated
  204.  
  205. 3    /B or /N switch was satisfied, processing terminated
  206.  
  207. Function change-all [@] always returns code 0.
  208.  
  209. variable $E is set to the ERRORLEVEL with the following exceptions:
  210. FOR USER INPUT
  211. 0-511 Ascii value of last key input. [3=Ctrl-C]
  212.       extended Ascii codes are 256-511
  213.       512 is set for timeout
  214.  
  215. when displaying the environment $E contains the amount of free space.
  216.  
  217.  
  218.                               USER INPUT
  219.  
  220.    ESET [switches] name prompt [valid-chars] [+-length] [time limit]
  221.  
  222.     Name is the variable name and can include one of the special
  223. operations from above [-+*^@], in which case the data input by the
  224. user will be used to perform the operation.
  225.  
  226.     Prompt is a string to be displayed.  If it contains blanks or <>|
  227. then it must be enclosed in "".  It cannot contain a ".
  228.  
  229.     Input is taken from Stdin and may be redirected.
  230.  
  231. SWITCHES
  232.  
  233. /E the current value of name is used as the default value which the
  234. user can edit.  An additional data item is required which is the
  235. maximum length for the item.  If the absolute value is not greater
  236. than the current length then the current length is used and the length
  237. cannot be increased.  If it is positive then the cursor will be
  238. positioned length+2 position from the beginning of the field.  If it
  239. is negative the cursor will be positioned 2 positions past the end of
  240. the input.  Currently, the total length of the prompt + the length of
  241. the input must be less than the length of 2 screen lines.
  242.  
  243. /A when the user enters a character into the last position, input is
  244. terminated and the code of that character is set in $E.  Applies only
  245. when /E is used.
  246.  
  247. /V An additional data item is required which specifies the valid
  248. input characters.  If a blank or <>| is allowed the list must be
  249. enclosed in "".  The blank must be given if allowed.
  250.  
  251. /Lnn the user has nn seconds to start responding.  After the first
  252. keystroke there is no time limit on completing.  the first keystroke
  253. does not have to be a valid character, when using /V, to stop the
  254. timer.  This must be last or only switch. [/EVL3 or /L5]
  255.  
  256. Switches VEA are toggles. Each occurrence reverses the state.
  257.  
  258. Ctrl-Z [eof] terminates all further input from STDIN but the command
  259. line is still processed.
  260. ie:         ESET A ? B ? C ? <DATA.FIL
  261. if DATA.FIL only contains one line then variables B and C would be
  262. cleared.
  263. ie:         ESET A ? <DATA.FIL
  264. if DATA.FIL contains more then one line the remainder of the file is
  265. ignored.
  266.  
  267.     The following control keys are available during keyboard input:
  268.  
  269. Right and left cursor, backspace, delete, home, end, insert
  270.  
  271. Ctrl-left and Ctrl-right move to the next word.
  272.  
  273. Ctrl-home restores the default value.
  274.  
  275. Ctrl-end clears from the cursor to the end of the input.
  276.  
  277. Ctrl-C [break] terminates all further processing of the command line.
  278.  
  279. Any other non-character key terminates input.
  280.  
  281.                               TECHNICAL
  282.  
  283.     Because of the way the environment is manipulated an existing
  284. variable maintains the same sequential position within the
  285. environment.  They are not moved to the end when they are changed.
  286. This may be of some use otherwise but I mention it mainly because they
  287. would not show on the display in the usual place.
  288.  
  289.     If using variables longer than 128 characters you should be sure
  290. and test them with your programs since some copy the environment into
  291. their own workspace and therefore may have problems with long ones.
  292. If you have trouble with a program locking up after using this, remove
  293. the long variable and test it again.
  294.  
  295.     Certain limitations, such as no " in a prompt string can be over
  296. come by setting a variable and using it.
  297. ie: ESET Y="huh?" Z %%Y would use the string "huh?" as the prompt.
  298.  
  299.     One common problem is getting the DOS message, "Bad command or
  300. file name", because the command is too long.  This can be avoided by
  301. using %% for variables.
  302.  
  303.     Nested variables are available where DOS does the first
  304. replacement and ESET does the next.
  305. Given: Y contains the value %Z% and Z contains HI
  306.       ESET Y=%%%%Z Z=HI
  307. Then: ESET A=%Y% in a BAT file would set A to HI.
  308.  
  309.        Mailing address:
  310.  
  311.                  Wayne D. Mingee
  312.                  314 N. Main St.
  313.                  Bridgewater, Va 22812
  314.  
  315.     Bug reports or suggestions may be sent to the above address or
  316. Messaages can be left at one of the following BBS.
  317.  
  318.   Mad Hacker           703-433-0824 Harrisonburg, VA
  319.   Computer Connection  202-547-2008 Alexandria, VA
  320.